home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Turnbull China Bikeride
/
Turnbull China Bikeride - Disc 1.iso
/
ARGONET
/
PD
/
SOUND
/
XPRMOD.ZIP
/
XprMod
/
Guide
next >
Wrap
Text File
|
1998-08-25
|
10KB
|
350 lines
Documentation for XprMod v1.10
(Tab width 8)
XprMod by Skoe of Expression
Thanks to MikMak for many sources!
================================================================
Introduction
================================================================
XprMod is a multitrack, multiformat (multimedia, hehe) sound
module player. It can play up to 32 channels with real panning
(stereo) effects and on fast processors with interpolation.
This version can load various PC, Amiga and Atari MOD files,
XM, S3M and MTM. Other formats will be added in future versions.
Several SWIs can be used to control the player, see below. You
can (and shall) use the auto-setup option to get the best
quality on fast processors (ARM7, SA110) and the highest speed
on slow ones (ARM 3).
XprMod runs also on cacheless processors, but they are history
and so nothing is optimised for these ones. I could make the
player about 30% faster on ARM2, but it's a senseless waste of
time.
Don't use it for tracks with 8 voices or less - convert them!
Players like DigitalSymphony or MatrixTrack8 (using the 8
physical channels of the Acorn sound system) are much faster
with these tracks than XprMod, because it uses always software
mixing. Perhaps I will implement 2 different routines later...
================================================================
Copyright
================================================================
XprMod is based on MikMaks MikMod. It is no simple port but
was totally revised and partly re-written. Future releases will
have only less in common with MikMod, because even the internal
structure of this player and most routines will be changed.
You may (and must :) use XprMod (unchanged) in your products.
Please credit me with something like "Music player by Skoe of
Expression". If you use it in a commercial product of any kind
(CD-ROM's, Games etc.) and you'll sell more than 20 copies of
it, you must (!) give me 20 pounds or a free copy of this
product. If you don't do that, it is a violation of the copy-
right laws!
If you include the player module as a single file into your
application, please copy this file into it, too. You needn't do
this if you have real problems with space (e.g. a 1599 kB demo).
The author of this player will not be responsible for any
loss or damage caused by this software.
My addy:
Thomas Giesel
Hauptstr. 61
D-03246 Crinitz
Germany
================================================================
Speed
================================================================
It is possible to play
- up to about 10 channels on ARM2 with 14kHz (in a bad quality)
(but who cares about 8Mhz machines?!)
-> use DSym or similar programs !!!
- up to about 24 channels on ARM3
- up to 32 channels with 41kHz mixing and interpolation
on SA110 (needs 20% processor (or better: RAM) speed or less)
Following tests were made by Mr. Hill of Icebird (thanx!) with an
older XprMod v0.30:
SA110, 60ns RAM (RPC 600 board): 41kHz, real stereo, interpolated
XprMod QuantumPlayer(24µs) MatrixPlayer(24µs)
4 channel 6.38% 5.42% -not tested-
8 channel 8.47% -gave up- -not tested-
11 channel 12.24% -gave up- 23.54%
16 channel 16.41% -gave up- 24.91%
20 channel 14.30% -gave up- -not tested-
30 channel 21.71% -gave up- -not tested-
The player needs about half of the speed without interpolation
and real stereo mixing (depending on hardware configuration).
================================================================
Mixing Quality
================================================================
If you use the auto-setup option, you can be sure that the
player will find a good compromise between quality and speed on
nearly every machine.
You may choose following modes:
high quality:
use a high sampling frequency, real stereo (all panning
effects) and interpolate if possible
normal quality:
use a medium frequency and real stereo
fast mode:
use a low quality (max. 22kHz) and fast stereo mode (mix to two
fix stereo positions, panning disabled)
If the computer system to slow or to fast :) you could get also
15kHz with fast stereo mode when chosen "high quality" or
real stereo in "fast mode".
I offer you to use "high quality" in desktop players and music-
compilations, "normal quality" in demos and "fast mode" only if
you or your computer is ill. Or simple include a button...
================================================================
Fast Guide
================================================================
SYS"ExpressionMod_Load", "ADFS::4.$.XMFile", 0, -2
REM 0 -> file, -2 -> normal quality
SYS"ExpressionMod_Play", 1
REM 1 -> restart after end
Enough for a first test?!
- Don't forget to stop your track before exit your program
- Don't start other players while XprMod is playing! To get
a higher speed XprMod and most other players are not 100%
Acorn conform and could crash or play strange sounds.
================================================================
Software Interrupts
================================================================
temporary SWI chunk base number 0x8A800, NOT allocated by Acorn
- Use it on your own risk !!! -
Note: "Returns error block" means: if an error is occurred,
the SWI will return with V set and R0 pointing to a
standard Risc OS error block. If the SWI X-bit is not
set, the OS will report the error as usual.
If nothing unpleasant happened the registers return
like described.
================================================================
SWI ExpressionMod_Load base + 0x00
================================================================
Use this SWI to load a file from a FS or RAM and to choose the
quality. If the file doesn't exist or cannot be loaded, an error
will be returned. Loading could take some seconds, because the
track will be converted into an internal format. This is the
only chance to change the setup, after loading you can't do it.
Entry:
R0 pointer to filename (or pointer to track in
memory if R1 > 0)
R1 0 to load from file, else length of track
in memory
R2 quality
if minus: auto setup DEPENDING FROM SYSTEM SPEED
for detailed notes see chapter "Mixing Quality"
-1: try to use high quality
(interpolated, real stereo,
high mixing frequency)
-2: normal
(real stereo, normal mixing
frequency)
-3: fast, (avoid this mode!)
(left - right only, low freq)
else: custom setup
bit 0: interpolate samples
bit 1: use real stereo mixing
R3 mixing frequency only if custom setup
14000 <= R2 <= 41000, other values will become
clipped
R4 0 !!! (for future extensions, not tested yet)
Exit:
returns error block or
all preserved
================================================================
SWI ExpressionMod_Play base + 0x01
================================================================
After loading or pausing you can (re)start playing with this
SWI. It is possible to repeat a song or to play it only once.
After playing once, ExpressionMod_Stop will be called
automatically. It is not impossible that an error occurres!
Entry:
R0 = 0 for playing only once
anything else for repeating song
(ignored at restart after pausing)
R1 = 0 (for future extensions)
Exit:
returns error block or
all preserved
================================================================
SWI ExpressionMod_Pause base + 0x02
================================================================
Does not detach the channels, only stops playing until
ExpressionMod_Play was called.
Entry:
-
Exit:
all preserved
================================================================
SWI ExpressionMod_Stop base + 0x03
================================================================
Stop playing and discard loaded song.
Entry:
-
Exit:
all preserved
================================================================
SWI ExpressionMod_Position base + 0x04
================================================================
You can set the song position (patter number) and/or read the
position and row number. This can be done before starting,
while playing or pause.
Entry:
R0 = 0 to read
or
R0 position to set
Exit:
R0 position (pattern number)
R1 row
rest preserved
================================================================
SWI ExpressionMod_Info base + 0x05
================================================================
Read various infos.
Entry:
-
Exit:
R0 pointer to songname
R1 pointer to modtype
e.g. "FastTracker v2.00"
R2 number of logical channels
R3 number of patterns
R4 used mixing frequency in Hertz
R5 mixing mode:
bit 0 set if interpolated (else normal)
bit 1 set if real stereo (else fast left/right)
================================================================
SWI ExpressionMod_Volume base + 0x06
================================================================
Set volume 0 (silent) to 128. Forbidden values will be treated
as 128. No error returning necessary. This can be done always.
Normally the amplifier uses the right setting for a high volume
without distortion. Nevertheless it may happen that the player
overdrives and plays crackling sounds. In this case choose a
lower volume.
Entry:
R0 volume
Exit:
all preserved
================================================================
SWI ExpressionMod_Prev base + 0x07
================================================================
Jump to previous pattern (if existing).
Entry:
-
Exit:
all preserved
================================================================
SWI ExpressionMod_Next base + 0x08
================================================================
Jump to next pattern (if existing).
Entry:
-
Exit:
all preserved
EOF